Device Template File Properties

The IoT EIE sample device template files include sections specific only to the IoT EIE. This topic contains three examples of IoT-specific device template files and how they connect with payloads.

Device Template Elements and Attributes for the IoT EIE

Data in device templates define what the payload looks like and where to find specific items in the payload. The payloadDef section of an IoT EIE device template file contains elements and attributes that define the payload.

Note: If a timestamp is not included in a payload item, the topic's timestamp is used. When a topic does not include a timestamp, the CygNet host's timestamp is used.

Payload Definition

The following table lists and describes elements found in the payloadDef section of the IoT EIE template files.

Element Description

mapTypes

Maps data types in the payload to CygNet data types.

ex

Each enumeration must begin with a lowercase e. It is then to be followed by a data type defined in the payload (e.g., data type 1 is represented as e1 and data type "UInt" is represented as eUInt.)

Each enumeration element must be unique, but its value does not need to be unique. For example, using e1 twice within a single enumeration list is illegal, but using the value "ui2" for e1 and e2 is legal.

Each enumeration must use a value attribute to define a constant value that corresponds to a valid CygNet data type.

mapUnits

Maps units in the payload to CygNet units. This section is needed only when the payload indicates data units that you want to import into CygNet.

For example, CygNet represents kilograms as "kg", while a payload may use the text "KGRAM". This section of the device template file can be used to map the text string "KGRAM" from the payload to "kg" in CygNet.

ex

Each enumeration must begin with a lowercase e. It is then to be followed by a "units" value defined in the payload (e.g., units "KGRAM" in the payload is represented as eKGRAM.)

Each enumeration element must be unique, but its value does not need to be unique. For example, using eKGRAM twice within a single enumeration list is illegal, but using the value "kg" for eKGRAM and eKILOGRAM is legal.

Each enumeration must use a value attribute to define a constant value that corresponds to a valid CygNet unit. See PNT Engineering Units.

paths

Identifies a set of path IDs.

<pathid>

Provides a path to items in the payload file (e.g., pMetric or pPayload). This value is user defined and unique to the device template.

where

Defines a set of clauses used to correlate a payload item to a data group element.

formats

Identifies a set of format IDs.

<format ID>

Identifies the format of a payload item (e.g., fMetric or fPayload). This value is user defined and unique to the device template.

value

Specifies the value of the payload item.

type

Defines the data type of the payload item.

dateTime

Defines the timestamp of the payload item.

isHistory

Denotes whether the payload item represents a historical value. Default is false.

isNull

Denotes whether or not the payload item has a value. Default is false.

units

Defines the units of the payload item.

Payload Definition Attributes

The following table lists and describes IoT-specific attributes found in the payloadDef section of the IoT EIE template files.

Attribute Description

value

value specifies a constant value of a payload item.

path

The location of the item in the payload file. If the path is blank or missing, use the root node.

Note: The path allows the following substitution strings:

  • %deviceId%
  • %facilityId%
  • %ordinal%

formatId

Identifies which format ID value from the formats element within payloadDefs to use with this path. If the format ID is blank or missing, each key in the payload represents a value.

key

Represents the identifier from the payload.

attribute

Identifies an attribute of a data group element.

type

Defines the data type to associate with a payload key.

Value:
  • boolean: Boolean
  • i1: Character
  • i2: Short integer
  • i4: Integer
  • i8: Integer
  • r4: Float
  • r8: Double
  • ui1: Byte
  • ui2: Unsigned short integer
  • ui4: Unsigned integer
  • ui8: Unsigned integer
  • string: String

cvtF

Specifies the conversion method used to convert source data of one format into a different target format. Specifically, it is used to convert a payload timestamp to a COleDateTime double. See cvtF Conversion Method.

Data Group Attributes

The following table lists and describes IoT-specific data group attributes.

Attribute Description

setUnreliableOnLostConnection

If setUnreliableOnLostConnection is set to "true", all CygNet points will be set to unreliable upon receipt of a DEATH message for the topic associated with the data group. Otherwise the point status is unchanged.

The data group element _goodConn must be defined to identify the payload item that indicates connection status.

Data Group Elements

The following table lists and describes IoT-specific data group elements. These items are optional, but have special meaning in CygNet. If used, each item must have an itemId mapping it to a payload item.

Data Group Element ID Description

_topicTime

The topic/payload data time. This value is used for point processing in the absence of a timestamp associated with each payload item.

_goodConn

Boolean value indication that the MQTT connection to the remote device/node is good.

Data Group Element Attributes

The following table lists and describes IoT-specific attributes of data group elements.

Attribute Description

itemId

The required name of the item in the payload file. This is used to map an item in a payload file to a CygNet data group element.

Note: The itemId allows the following substitution strings:

  • %deviceId%
  • %facilityId%
  • %ordinal%

pathId

Identifies the path from the Payload Definition used to locate this item.

type

It is recommended that type variant ("vrnt") be used to preserve the data type provided in the payload.

IoT_Sample.dtf

The following example displays a sample section of the IoT_Sample.dtf.

Example

<payloadDef>

<mapTypes>

<e1 value="i1"/>

<e2 value="i2"/>

<e3 value="i4"/>

<e4 value="i8"/>

<e5 value="ui1"/>

<e6 value="ui2"/>

<e7 value="ui4"/>

<e8 value="ui8"/>

<e9 value="r4"/>

<e10 value="r8"/>

<e11 value="boolean"/>

<e12 value="string"/>

<e13 value="ui8"/>

<e14 value="string"/>

</mapTypes>

<paths>

<pMetric path="metrics" formatId="fMetric">

<!--path => $.metrics[?(@.name = /%itemId%/)]-->

<where>

<w key="name" attribute="itemId"/>

</where>

</pMetric>

<pPayload path="" formatId="">

<!--blank/missing formatId => each key represents a value-->

<!--blank/missing path => use root node-->

</pPayload>

</paths>

<formats>

<fMetric>

<value key="*value">

<!--note wildcard; key could be value, int_value, intValue-->

</value>

<type key="datatype"/>

<dateTime key="timestamp" type="ui8" cvtF="TimeMs"/>

<isHistory key="is_historical"/>

<isNull key="is_null"/>

<units key="properties.Unit.value"/>

</fMetric>

</formats>

</payloadDef>

<dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true">

<Topic1 niceName="Topic 1">

<dgElements secLev="4" type="vrnt" pathId="pMetric">

<_topicSeq desc="Seq #" itemId="seq" pathId="pPayload"/>

<_topicUuid desc="UUID" itemId="uuid" pathId="pPayload"/>

<_topicTime desc="Date/time (#)" itemId="timestamp" pathId="pPayload" cvtF="TimeMs" sourceType="ui8" type="r8" hidden="true"/>

<_topicTs desc="Date/time (UTC)" ref="_topicTime" type="string" format="DateTime"/>

<SignedI1 desc="Signed byte" itemId="sbyte1"/>

<SignedI2 desc="Signed word" itemId="sword1"/>

<SignedI4 desc="Signed double word (scaled)" itemId="sdword1" cvtF="Scale" sourceType="i4" type="r4" scaleFactor=".01" units="in"/>

<SignedI8 desc="Signed quad word" itemId="sqword1"/>

<Unsigned1 desc="Unsigned byte" itemId="ubyte1"/>

<Unsigned2 desc="Unsigned short word" itemId="uword1"/>

<Unsigned4 desc="Unsigned double word" itemId="udword1"/>

<Unsigned8 desc="Unsigned quad word" itemId="uqword1"/>

<Float desc="Float" itemId="float1"/>

<Double desc="Double" itemId="double1"/>

<Bool desc="Boolean" itemId="boolean1"/>

<String desc="String" itemId="string1"/>

</dgElements>

</Topic1>

</dataGroups>

Payload

The payload is the actual message content. The following is an example section of a payload file for the IoT_Sample.dtf.

{

"timestamp":"1540853441117",

"seq":1

"metrics" : [ {

"name" : "sbyte1",

"datatype" : 1,

"intValue" : 4294967295

}, {

"name" : "float1",

"datatype" : 9,

"floatValue" : 2.22865694E-7

}, {

"name" : "boolean1",

"datatype" : 11,

"booleanValue" : false

}, {

"name" : "string1",

"datatype" : 12,

"stringValue" : "String4321"

} ],

}

Payload Properties

The following table lists and describes IoT-specific attributes found in the sample payload file above.

Property Description

timestamp

Represents the time at which the message was published. The value is an unsigned 64-bit integer representing milliseconds since 1/1/1970

seq

The sequence number in the payload.

metrics

An array of payload items.

name

The item identifier correlates to the itemid value in an IoT data group.

datatype

This value in the payload must also appear in the mapTypes element of the device template.

*value

The value of the payload item. The * denotes a wildcard. For example, the key could be value, int_value, or intValue.

Back to top

IoT_SampleSingleItem.dtf

The following example displays a sample section of the IoT_SampleSingleItem.dtf.

Example

<payloadDef>

<mapUnits>

<eKGRAM value="kg"/>

<eFEET value="feet"/>

</mapUnits>

<paths>

<pPayload path="" formatId="fPayload">

<!--blank/missing path => use root node-->

</pPayload>

</paths>

<formats>

<fPayload>

<value key="*value"/>

<dateTime key="ts" type="string"/>

<units key="units"/>

</fPayload>

</formats>

</payloadDef>

<dataFormat/>

<dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true">

<Hydro niceName="Hydro">

<dgElements secLev="4" type="ui4">

<Hydro desc="Hydroelectric usage" pathId="pPayload"/>

</dgElements>

</Hydro>

</dataGroups>

Payload

The payload is the actual message content. The following is an example section of a payload file connected to the IoT_SampleSingleItem.dtf.

{"ts": "10/24/2024 14:35:00", "value": 3232, "units": "KGRAM"}

Payload Properties

The following table lists and describes IoT-specific attributes found in the payload file.

Property Description

ts

Represents the time at which the message was published.

value

The value of the payload item.

units

Defines units of the value.

Back to top

IoT_SampleKeyValue.dtf

The following example displays a sample section of the IoT_SampleKeyValue.dtf.

Example

<payloadDef>

<paths>

<pHeader path="" formatId="">

<!--blank/missing path => use root node-->

<!--blank/missing formatId => each key represents a value-->

</pHeader>

<pData path="data" formatId="">

<!--blank/missing formatId => each key represents a value-->

</pData>

</paths>

</payloadDef>

<dataFormat/>

<dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true" setUnreliableOnLostConnection="true">

<Topic1 niceName="Topic 1">

<dgElements secLev="4" type="vrnt" pathId="pData">

<_topicTime desc="Date/time (#)" itemId="createTime" pathId="pHeader" cvtF="TimeString" format="ISO8601" hidden="true"/>

<_topicTs desc="Date/time" ref="_topicTime" type="string" format="DateTime"/>

<_goodConn desc="Connected to device" itemId="connected" pathId="pHeader"/>

<gwName desc="Gateway name"/>

<devName desc="Device name"/>

<BoolTag1 desc="Boolean 1"/>

<BoolTag2 desc="Boolean 2"/>

<BoolTag3 desc="Boolean 3" itemId="00003"/>

<BoolTag4 desc="Boolean 4" itemId="00004"/>

<AnaTag1 desc="Analog 1"/>

<AnaTag2 desc="Analog 2" itemId="40002"/>

<FloatTag1 desc="Float 1"/>

<StringTag0 desc="String 0" itemId="47002"/>

<StringTag1 desc="String 1"/>

<StringTag2 desc="String 2" itemId="49002"/>

<rtuIsAlive desc="RTU is alive"/>

<SeqNumb desc="Seq number"/>

</dgElements>

</Topic1>

</dataGroups>

Features of the device template file:

Payload

The payload is the actual message content. The following is an example section of a payload file consisting simply of a group of key-value pairs. This is the simplest type of payload to define.

{

"createTime": "2023-04-09T10:32:02.011Z",

"connected": "true",

"data": {

"gwName": "GatewayName",

"devName": "FieldUnit",

"BoolTag1": false,

"BoolTag2": false,

"00003": false,

"00004": false,

"AnaTag1": 40,

"40002": 50,

"FloatTag1": 123.456,

"47002": "",

"StringTag1": "This is a string value",

"49002": "This is another string",

"rtuIsAlive": true,

"SeqNumb": 0

}

}

Back to top